Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / applic / ntp / acts.arc / NBSTIME.DES < prev next >

Wrap

Text File | 1988-10-14 | 62.7 KB | 1,049 lines

NATIONAL BUREAU OF STANDARDS EXAMPLE SOFTWARE FOR USING THE AUTOMATED COMPUTER TIME SERVICE (ACTS) Program Name: NBSTIME Usage: NBSTIME [ -d ] This program is used to set or check the date and time on an IBM personal computer (or equivalent) using data obtained by dialing the NBS using a Hayes- compatible modem connected to the computer via one of the COM ports. It can also be used to provide an output pulse on the line-printer port once per second to synchronize other devices. <*2> Other versions of this program have been developed for performing the same functions on other hardware. These variants are described in more detail in Appendix A. The different operating modes are selected by means of a configuration file. A separate program called MAKCFG (described in more detail below) can be used to make this file based on your answers to a series of questions. You may also generate or modify this file using any text editor. Once the configuration file is prepared, you start the program by typing the command NBSTIME <return> in response to the system prompt. The switch -d on the command line is optional. If present, it specifies debug mode, and causes various intermediate parameters to be written to the screen. The default is no debug mode. The brackets enclosing the -d are meant to signify that the switch is optional. They are never entered on the command line. See the section below on operating instructions for more information. The Configuration File The name of the configuration file is nbstime.cfg. It must be located in the same directory from which the program will be run. The configuration file may be prepared with a text editor such as EDLIN. Alternatively, it may be generated using program MAKCFG, described below. <*1> The file contains 5 or 6 lines in the following format: Line 1: Dialing mode and telephone number. The first character on line 1 must be P, T or M. P means that the modem will dial the telephone number using pulse mode (which emulates a rotary dial mechanism), T is for tone mode (which emulates push-button telephones) and M is for manual dialing (which means that the telephone connection will be completed manually outside of the program). In pulse mode or tone mode, the remaining characters on the line are the digits 0 - 9, a space or a comma. (Some modems will also accept the * and # symbols as part of the telephone number in tone mode and will dial them as well). The telephone number is not modified by the program and the entire string is passed to the modem. This line must contain the complete telephone number including long-distance access and area code (if necessary) and any other accounting digits as needed. A comma signifies a pause for 2 seconds to wait for another dial tone, and spaces may be inserted to improve legibility. For example: T 9, 987 6 5 4 3 means dial 9, wait 2 seconds and then dial the remaining digits. All digits are dialed in tone mode. The telephone number must be less than 30 characters long including embedded blanks. If the first character is M, then manual dialing is specified and the remainder of the line is ignored. The program will prompt you to dial the telephone manually and will wait until you indicate that the connection is completed. <*1> Line 2: The first character specifies which communication port will be used. There are two versions of the program which differ in which ports they can use (see below for more details). If the version that uses direct calls to the BIOS is used (called NBSTIMEB.EXE on the distribution disk), the first character must be 1 or 2 to specify communication via COM1 port or COM2 port, respectively, since only these ports are supported by the internal BIOS routines. If the version that controls the ports directly is used (called NBSTIMED.EXE on the distribution disk), the first character may also be 3 or 4 to specify ports COM3 or COM4, or it may be h (or H) to signify that the COM port will be specified by its hardware address on line 6 (see below). This character must be set to match the port to be used. The second character on the line may be B (or b) or E (or e). This character specifies whether the program is to expect responses to various dialing commands from the modem. E specifies echo mode: the program expects that characters sent to the modem in command mode will be echoed and that the modem will respond OK to a command; B specifies blind operation. Some modems can be configured either way either by a switch or the Q command. (A modem configured by the Q command will revert to the switch default upon reset.) If the second character on the line is neither B nor E, then E is set by default. Note that when the program is configured for echo mode (by specifying E explicitly or by default) then it will insist on responses and will abort if they are not received. The third character on the line specifies the communication speed (and, implicitly, the communication protocol). If the third character is h (or H), then 1200-bits/s high-speed communication is selected using the 212A-type protocol. If l (or L) is used, then 300-bits/s low-speed service is selected using 103-type protocol. Many modems are capable of operating at either protocol (such dual-speed modems are often identified as "300-1200" type) and will switch to the correct speed and protocol automatically when then are activated. Triple-speed modems of the "300-1200-2400" type may also be used at either 300 or 1200 bits/s. Different messages are transmitted depending on the speed selected. The message transmitted at 1200-bits/s contains the full date and time, including the Daylight-Savings Time flag and other information. This service is intended for users who want to set or check the time of the computer clock with an uncertainty on the order of 10 - 20 milliseconds (0.01 s - 0.02 s) limited by the resolution and accuracy of the internal computer clock. See the discussion below for more information. The message transmitted at 300-bits/s is shorter because of the slower transmission speed, and contains only the time and the estimated line delay in milliseconds. Therefore, it is not possible to set the computer clock since neither the date nor the correction for Daylight Savings Time are transmitted (the conversion to local time in the United States, for example, will change the date about 30% of the time, and the correction for Daylight Savings Time is necessary about 50% of the time. It would be possible to assume that the computer date is correct, but the program does not do so.). This service is intended for users who are more interested in the timing pulse capability (to be described below) or who design special-purpose systems that can make use of the full capability of the transmissions. The fourth character on this line selects a timing-pulse capability. If this character is y (or Y), then a negative-going pulse (from +5 v to 0 v) is sent to the strobe line of the line-printer port (LPT1) every second upon receipt of the on-time marker (the * or # symbol at the end of each transmitted line) from NBS. The pulse is sent to pin 1 of the DB25 female connector used for the standard line-printer interface. Pin 25 of the same connector is at ground potential. The leading-edge of the pulse is delayed from receipt of the on-time marker by a time on the order of micro-seconds, depending on the speed of the computer. The pulse is approximately 20 micro- seconds wide. This pulse is normally used by the printer interface software to transfer a character from the computer to the line printer (-strobe), so that the printer should be disconnected if this capability is enabled. <*1> There are three types of commonly used line-printer interfaces. One of them is part of a combined monochrome display and printer adapter. The second is just a printer adapter and the third is a combined serial/parallel adapter that is normally found only on AT-type machines. The command register address for the first type is 3be (hex), while the second types both use 37a (hex). If the strobe capability is enabled, the program obtains the address of the adapter from address 410 (hex) in low memory. (Note that address 410 hex is offset 0 in paragraph 41 hex). If location 410 (hex) is zero or if the adapter does not respond to a test pulse, the program will print a diagnostic message to that effect, the pulsing capability will be disabled and the program continues. The fifth character on the line determines whether or not the received data will be used to set the computer clocks or merely to check them. If this character is s (or S), then the clocks are set and then verified by comparing the time read from the internal clocks with the next line received from the NBS (both the received time and the internal clocks will have advanced by one second between the time they were set and when they were checked). This mode does not preserve the time of the clocks before they were set and does not provide any information on the performance of the clocks. If this character is d (or D) then the clocks are only compared. The NBS time, the computer time and their difference are typed on the screen. This mode preserves the time of the clock (since it is not set), and can also be used to give an estimate of the rate error (how much the computer clock is gaining or losing with respect to NBS). The rate error (expressed in seconds per day, for example) is simply the time difference in seconds reported by the program divided by the number of days since the clock was last set. This mode of operation is intended for users who want to characterize the performance of their clocks by observing their accuracy over extended periods of time. The effect of this switch also depends on the AT switch (described below). An IBM AT-type machine has two clocks -- one whose time is stored in the volatile memory and which is updated by the ROM BIOS only when the computer is turned on and one which is powered by a battery and which runs continuously. Other models (such as the XT-class machines) do not have a battery clock. This switch enables or disables the setting of BOTH clocks for an AT-class machine and only the memory-based clock for other models. That is, both clocks are either set and verified or just compared. <*2> The sixth character on the line is used to enable storing time- difference measurements in a file for subsequent more detailed analysis. If this character is a, the time difference between the computer clocks and the NBS is stored in a file named NBSTIME.DIF. The program writes the current time difference to the end of the file (if it currently exists) or creates a new file if it does not. The time difference is written in the form: year, month, day, hour, minute, second, difference of volatile memory clock and difference of battery clock (if it exists). The year, month, etc. are taken from the NBS transmission and the difference is a signed number which is positive if the computer clock is fast and negative if it is slow. The difference is followed by a single letter giving the units: d, h, m, s for days, hours, minutes and seconds respectively. This computation is separate from the setting or checking modes described above. It is performed when the fifth line is received from NBS, so that the difference will be written to the file BEFORE the clocks are set (if that option is specified). Although the action of this switch is independent of whether the clocks are set, the interpretation of the data is not. If the fifth character specifies that the clocks shall always be set, then the difference written to the file by this operation is the time error that has accumulated since the last NBS access, since the clocks were corrected at that time. If the fifth character specifies that the clocks are not to be set, however, then the time error is the cumulative error since the clocks were last set, and the error since the last NBS access is the difference between the current and previous values for the differences. <*2> If this character is A, then in addition to writing the current differences to file NBSTIME.DIF as described above, the program will compare the current differences against the values that were estimated the previous time (i.e. the values found at the end of the file when the program was first activated). The previous differences are subtracted from the current estimates, and the results are divided by the time that has elapsed since the last value was stored in the file. The result is an estimate of the rate of the computer clock with respect to NBS. These rate estimates are printed on the terminal in units of seconds per day, where a positive value means that the computer clock is running faster than the NBS rate. The uncertainty of this rate estimate is discussed below. <*2> If this character is n (or N), then the time difference is not stored in the archive file and the rate estimate is not computed. Note that this is the only parameter whose effect is different in upper or lower case. The remainder of this line is ignored and may contain any characters. Line 3: This line specifies the time zone of the user. This parameter is used to convert the time transmitted by the NBS from universal time to local time. The parameter represents the value of local time minus Universal time in hours. Locations West of Greenwich are negative, while those East are positive. If specified by value, the value should not exceed 12 hours, but this is not checked. The zone may be specified by name or numerically as follows: First character on line Action Offset in hours P or p U. S. Pacific Time -8 M or m U. S. Mountain Time -7 C or c U. S. Central Time -6 E or e U. S. Eastern Time -5 Z or z Greenwich Time 0 + or - or digits Number read defined by number In all cases, the remainder of the line is ignored. Thus the following lines are equivalent: Mountain Standard Time m -7 The Rocky Mountains are here The program does not support conversion to local time in half-hour zones (i.e. zones where the time difference between local time and Universal time is not an integral number of hours). <*1> Program MAKCFG (see below) also allows the user to specify any time zone by its letter. If that method is used, MAKCFG converts the letter to its equivalent numerical offset. See MAKCFG for more details. Line 4. If the first character is 1, then the user observes Daylight Savings Time, and the local time will be adjusted accordingly if necessary, based on the Daylight Savings Time flag transmitted by NBS. If the first character is 0, the Daylight Savings Time flag is ignored and no such adjustment will be made. No other characters are permitted on this line. If you use a 1 here, then the time will be advanced by one hour if the NBS transmission indicates that Daylight Savings Time is currently in effect. You will need to use 0 if you live in an area that does not observe Daylight Savings Time at all (such as Arizona), or if you change to Daylight Time on a different day from the national standard. Line 5. This is called the AT-flag. If the first character is 1, the user has an AT-type machine with a CMOS battery clock, and the program will set or check it (in addition to the clock that is stored in memory). If the first character is 0, the CMOS clock is neither set nor checked. Zero is appropriate for users who do not have a CMOS battery clock or who have this type of equipment but do not want it to be used. Note that the time stored in the volatile memory clock is lost when the power is removed, so that you should probably set and check the battery clock if you have it. The remainder of this line is ignored and may contain any characters. <*1> Line 6. This line is optional. It is only necessary if you are using the direct-access version of the program (NBSTIMED on the distribution) and if the first character on line 2 is h (or H), indicating that the COM port is to specified in terms of its hardware address. In that case, the hardware address must appear on this line beginning in column 1. The address must be specified in hex and is usually three digits long. The usual values for COM1 and COM2 are 3f8 and 2f8, respectively. This specification is not necessary if you use standard COM1 or COM2 ports, since the addresses of those ports can always be obtained by the program. It is also not necessary if you use COM3 or COM4, and if the addresses of these ports are stored in the BIOS data tables (at addresses 0:404 and 0:406, respectively). Although these locations are reserved for the addresses of COM3 and COM4, many versions of the BIOS do not use them. If this is the case in your system, then the program will halt with the message, "Port not in configuration" if you try to use specify COM3 or COM4 using a 3 or a 4 as the first character on line 2. In that case you must place an 'h' in col 1 of line 2 and you can then specify the hardware address here. The hardware address can usually be obtained from the installation manual provided by hardware manufacturer. Typical values for COM3 and COM4 are 3e8 and 2e8, respectively, but other values may be used on your system. Hardware Requirements The program will run on an IBM computer or equivalent. The computer must contain at least one serial port configured as a standard COM port with an external modem compatible with the Bell System 212A standard (1200 bits/s) or the 103 standard (300 bits/s) and capable of responding to the Hayes dialing commands. Internal modems and multiple speed modems that emulate these configuration are acceptable. If the output pulse capability is selected, the computer must have a parallel output port for a line-printer that is configured as LPT1. The address of the port can be either 37a (hex) or 3be (hex). The former is used by the printer adapter and the combined serial/parallel adapter, while the latter is used for the printer portion of the combined monochrome display/printer adapter. If this capability is enabled, the printer should be turned off or disconnected from the computer before the program is started. Software Requirements <*1> Program NBSTIMEB uses calls to the standard IBM DOS and BIOS routines except for the output pulse option that directly accesses the parallel output port. This version is isolated from the vagaries of the hardware by the BIOS, and it is likely to work with non-standard hardware that emulates the IBM standard using a custom BIOS. It can only use ports COM1 or COM2, however, since those are the only ports supported by the standard BIOS routines. It also requires that the modem assert the Clear-to-Send line (CTS) before the connection is made. Again, that is a requirement of the standard BIOS. Program NBSTIMED uses calls to the IBM DOS and BIOS routines to set and read the clocks, but input and output are performed by direct commands to the hardware ports. This version of the program can access all four COM ports and does not require that the modem assert CTS, but its operation depends on the detailed hardware configuration and is therefore less likely to work with third-party equipment that does not emulate the IBM personal computer at the hardware level. Both versions are written entirely in Borland Turbo C under DOS 3.2 (with no assembly language code), but are likely to work under earlier versions of DOS back to 2.0. Either version can be generated by altering a constant in the configuration file NBSTIME.H (supplied with the source code) and then recompiling the affected modules (see below). Transmission Format When the telephone connection to the NBS time service is completed, the NBS hardware sends timing information at either 300 bits/s or 1200 bits/s using standard ASCII characters. A line of information is sent every second, and the transmission continues for a predetermined number of seconds after which the connection is automatically broken. The two transmission speeds use different formats. In the high-speed (1200 bits/s) service, each line begins with a five- digit integer giving the Modified Julian Day Number (which advances by 1 every day and is about 47000 in 1988), and the year, month, day, hour, minute and second in Universal (Greenwich) Time. This time will be correct upon receipt of the terminating character (* or #) to be described below. The next parameter is the Daylight Savings Time flag. Values from 50 to 1 indicate the Daylight Savings Time is currently in effect; other values (99 to 51 and 0) indicate that Standard Time is currently in effect. Values other than 50 or 0 indicate both the current time and the number of days left before a transition to the other time is needed. Next is the leap-second flag. Zero is the normal case. A value of 1 indicates that an extra second will be added following 23:59:59 (Universal Time) on the last day of the current month. This second will be called 23:59:60, and the second after it will be 00:00:00 of the next day. A value of 2 indicates that a second is to be dropped on the last day of the current month. The second following 23:59:58 will be 00:00:00 of the next day. Leap seconds are usually required about every 18 months and are most commonly added at the end of June or December. It is unlikely that the dropping of a second will be necessary in the near future. Note that the leap second transition is linked to Universal Time, unlike the Daylight Savings transition which is linked to local time. The next number is the estimated offset between UT1 (a time scale derived from the rotation of the earth) and UTC (a time scale derived from frequency standards). The units are in seconds in steps of 0.1 second. The next parameter is the estimated telephone-line time delay in milliseconds as determined by the NBS hardware. It is estimated as one-half of the average time it takes the terminating character to be sent to the user and returned. (Any user who intends to make use of this delay must echo the terminating character back using either hardware or software methods. If the terminator is not echoed back to NBS, a nominal delay is assumed.) The remaining characters on the line are UTC(NBS) and the terminating character. The terminating character will be a * if the delay has not yet been measured or is not stable, and will change to a # if 4 consecutive measurements yield consistent values. The NBS hardware uses the time delay estimated in this way to transmit the subsequent terminating character so that it will arrive on time at the user. If the user does not echo the terminator back to NBS, then a nominal delay is assumed and the terminator is sent using this nominal value. This nominal value is unlikely to be in error by more than 0.1 second unless the circuit is transmitted via satellite. Operating Instructions The program may be run from any directory on any disk. If necessary, copy the files nbstimed.exe (or nbstimeb.exe) and nbstime.cfg to the appropriate directory. If you will use program makcfg, then copy makcfg.exe to the same directory. Make that directory the default using the cd command. Edit the configuration file nbstime.cfg if necessary (or run program MAKCFG). Any text editor, such as EDLIN may be used for this purpose. (Word processing programs can also be used to edit the file provided that the output file is in standard DOS format. Note that this is not the default output format for most word processors.) When the files are ready, connect the modem to the telephone line and to the computer and execute the program. If the program is to be run from directory blah on disk c, for example: copy nbstime*.* c:\blah copy the files. copy makcfg.exe c:\blah c: change to c disk if necessary cd \blah set directory if necessary type nbstime.cfg type the configuration file on the screen to see if it needs to be modified. If it does, you may do so using an editor such as edlin, as shown below. Or, you may run program MAKCFG, described below to produce a new nbstime.cfg file. edlin nbstime.cfg . . . edit configuration file if necessary ex exit from the editor rename nbstimed.exe nbstime.exe rename either version as nbstime or rename nbstimeb.exe nbstime.exe nbstime run program Operating Sequence This is what happens when the program is run: 1. The command line is examined to see if it contains -d. If it does, then set the debug mode to 1 (turn it on); otherwise leave debug at 0. This parameter is used for testing the program and should not normally be specified. 2. Read the configuration file nbstime.cfg and set the various parameters. If an error is detected in reading the file, print a message and stop. If the configuration file does not exist in the default directory, then use a default configuration which is identical to the sample configuration file. 3. Initialize the com port to 300 or 1200 bits/s, no parity, 1 stop bit. If output pulses are requested, determine the address of the parallel printer port. If the address cannot be determined then print a diagnostic message and disable the output pulse selection. 4. Dial the number if necessary. If remote modem answers print connect message and proceed. If no answer or busy then print message and stop. If manual dialing was specified, print a message for manual dialing and wait for connection. 5. Read the first 6 lines and echo the terminating character back to NBS for measuring the transmission line delay. Send an output pulse when each terminating character is received if that capability was specified in the configuration file. Print these lines on the screen. The terminating character will be * initially and will change to # if the NBS hardware measures a stable transmission delay. If 300-bits/s service was specified, continue reading lines in this manner until the NBS breaks the connection; then hang up the local modem and exit. <*2> 6. If 1200 bits/s service and archive mode are specified, the time difference between the computer clocks and the NBS transmission is computed when the fifth line is received and stored in file NBSTIME.DIF. If a rate estimate was also requested, subtract the current values from the values that were at the end of file NBSTIME.DIF and divide the results by the time that has elapsed since the last communication. Convert the result to seconds per day. <*1> 7. If 1200-bits/s service is specified, then use the time of the 7th and 8th lines to set the computer clock (if setting was enabled). The time is set to the received time of the 8th line provided that it is exactly 1 second later than the time received in the 7th line. If the times of the two lines do not differ by exactly one second, then try again with the next two lines. This method minimizes the probability that the computer clocks will be set incorrectly as a result of a transmission error. If the AT flag is on, then both the memory clock and the CMOS battery clock are set. Adjust the time to local time and for daylight savings time as specified in the configuration file. Echo the terminator of this line back to NBS and send an output pulse if pulse selection is enabled. 8. Read the time of the next line received from NBS and compare the time with the current values of the computer clocks. (All of the clocks should have advanced by 1 second.) Print both the times and the time difference values on the screen. If the AT flag in the configuration file is set, then compare both clocks with the time received from NBS and print both sets of times and time differences on the screen. The memory-based clock "ticks" 18.2 times per second, while the CMOS battery clock in an AT-type computer "ticks" once per second. It is not possible to read or set either clock to better than one of its ticks, so that differences of one tick or less are not significant. (This is discussed in more detail below.) 9. If output pulses are not enabled, then hang up the modem and exit. If automatic dialing was selected, a % character is sent to NBS and the Hayes hang-up sequence is sent to the local modem. If manual dialing was selected, then the local modem is presumed to not understand the Hayes commands and the Hayes hang-up sequence is not sent. If output pulses are enabled then do not hang-up the telephone, but continue receiving lines as in paragraph 5 above until the NBS disconnects the call. Timing Accuracy The volatile memory clock in personal computers of this type (IBM-pc or equivalent) ticks approximately 18.2 times/second (about every 56 milliseconds), and the time is kept as the number of ticks past midnight. It is not possible to alter the tick fraction using calls to either DOS or the ROM BIOS. This has two significant consequences: 1. Since there are not an integral number of ticks/second, not all times can exist. For example, 00:00:01.00 is not an integral number of ticks after midnight and therefore can not be set and will never be read. The nearest times are 00:00:00.98 and 00:00:01.04. The average offset between any given time and the nearest time that can be set is 0.5 ticks or about 28 milliseconds. 2. Time intervals are also uncertain by up to 1 tick since the tick fraction when the time is read cannot be known to the program. Again, the average offset is 0.5 ticks (28 milliseconds). The CMOS clock in AT computers cannot be set to better than a second since it does not store fractions of a second. The seconds fraction must therefore be truncated or rounded when the CMOS clock is addressed. This will further limit the accuracy of the time following a re-boot of the system (since the CMOS clock is copied into the system RAM clock at that time). In addition to these errors in setting and reading the clock in this type of computer, there is a possible error in the computation of the telephone line delay. This delay is measured at the NBS as one-half of the time it takes the terminating character (* or #) to be sent from NBS to the distant computer and return to the NBS hardware. This method depends on the assumption that the transit time is reciprocal, i.e. that the time from NBS to the computer is the same as from the computer to NBS. This may not be true if the two paths are different; many 1200 bits/s modems also have delays that are not reciprocal. Modem delays vary from brand to brand and are on the order of tens of milliseconds. The accuracy of the computer clocks after they have been set is determined by the accuracy of the rate of the internal crystal-controlled oscillators. These rates are usually sensitive to temperature and other factors and are unlikely to be stable to better than about 1 part-per-million (about 0.1 seconds/day), so that errors in the time of this order are likely even if the time is set exactly initially. There may also be a problem with the date if the machine is run continuously, since the date in some computers is not advanced when the time passes through midnight. (This comment applies to the clock stored in memory only. The CMOS clock in AT-type machines advances the date properly, but this clock is only used to set the time initially when the computer is started.) This is a "feature" of the BIOS routines that manage the memory-based clock. The accuracy of the output pulse is limited primarily by the stability of the telephone line delay, since the delays within the computer are likely to be very small by comparison. Many modems contain equalizing circuits that attempt to measure the characteristics of the telephone line to which they are connected. The operation of these circuits may adversely affect the stability of the measured time delay. Although the measured delay may be quite stable from second to second (with fluctuations of less than 50 micro-seconds), it often changes significantly every few seconds (as much as 500 micro-seconds) as the equalizing circuits operate. The equalizing circuits are usually more important at the higher speeds so that this effect is likely to be smaller at 300 bits/s. <*2> The method used by the program to estimate the rate of the computer clocks may produce estimates that have large uncertainties if the program is run very often. The rate is computed by subtracting the current time difference from the previously estimated value and the result will be affected by the jitter in both estimates. The uncertainty of the result will be about 40% higher than the uncertainty of either of its constituent differences. This second difference (the difference of the differences) will have an average uncertainty of about 1.4 X 0.5 ticks or about 40 milliseconds (= 0.040 seconds). If the two program runs are 5 minutes (= 0.00347 day) apart, an uncertainty in the second differnce of 40 milliseconds translates into a rate uncertainty of 0.040/0.00347 = 11.5 seconds/day. This uncertainty is likely to be much larger than the true rate error of the clock so that a rate estimate done this way is unlikely to give an accurate estimate of the performance of the computer clock. If, on the other hand, the two program runs are 5 hours apart (= 0.21 day), the same uncertainty in the second difference translates into a rate uncertainty of 0.040/0.21 = 0.2 seconds/day. Thus, estimating the rate more often than 1 or 2 times per day is not recommended. <*2> A second difficulty with the rate-estimating process will occur if the program is configured to set the computer clocks. The time difference is written to the archive file BEFORE the clocks are set (see above). When the clocks are set, however, the time difference is set to zero, but a subsequent rate estimate does not take this into account and uses the last value found in the file even though it has been invalidated by the process of setting the clocks. Thus both the archiving process and the rate estimating process yield unambiguous values only if the clocks are not set. Fixing Problems If the program does not work, the following suggestions may be helpful. 1. First check the hardware configuration to be sure that it is connected, is in working order and is an IBM personal computer or functional equivalent. Likewise be sure that the modem is connected to the computer and to the telephone line and that it responds to the Hayes protocol. <*1> 2. Many modems have a small loudspeaker that is connected to the telephone line until the connection is made. Some modems also have lights to show the status of the call. The modem should start dialing within a few seconds after the program is initiated. If a loudspeaker is present, the dial tone should be heard followed by the dialing sequence. If lights are present, OH (off-hook) should light and SD and RD (send-data and receive data) should flash. If none of these things happens, be sure that the hardware is properly configured and that the configuration file specifies the correct port. If you are using NBSTIMEB, which uses the BIOS for input/output, it is possible that the dialing commands are not being sent to the modem. The IBM BIOS checks for various status indicators from the modem and will not initiate a transmission to the modem unless these status indicators are correct. In particular, DSR (Data Set Ready) must be true. In some modems this line follows DCD (Data Carrier Detect) and therefore will not be true until the telephone connection has been completed (this is logical for a modem used to answer incoming calls, but not for modems that can originate calls since they should be "ready" to accept a dialing command before the call is established). In this case, the modem will never be sent dialing instructions, since it will appear not ready at the start of the program. This may usually be changed by a switch in the modem. When set appropriately, this switch forces DSR and DCD to be true continuously. This adjustment is described in the instruction manual for the modem. It is often implemented as switch number 6. Note that changing the setting of this switch may change the operation of other programs, especially some terminal emulators that access the COM ports directly and not via the BIOS commands. In particular, Data Carrier Detect is normally used to indicate that the modem is receiving a signal from a distant modem over the telephone connection, and if this signal is forced to be continuously true, some terminal emulators may refuse to dial the modem, assuming that the connection is already established. NBSTIMED does not use the BIOS and is not limited in this way. 3. The error message, "No response from modem." means that the modem did not respond to the dialing sequence as expected. The message is followed by a number indicating how far into the sequence the error was sensed. Number 1 signifies no response to the initial command to reset the modem (ATZ). If this message is received, be sure that the hardware is okay and that the modem is connected to the COM port specified in the configuration file. Numbers 2 through 4 indicate no response to various parts of the set-up sequence. If this occurs, be sure that the echo/blind parameter on the second line of the configuration file is set appropriately and edit the configuration file (or rerun program MAKCFG) if necessary. A response of 5 is probably a telephone line problem -- since modem problems are likely to have resulted in a failure at an earlier stage in the process. These problems can usually be diagnosed by listening to the progress of the call on the built-in loudspeaker, if possible. Be sure that the telephone number is correct and that any long- distance codes have been entered correctly. If a pause for a second dial-tone has been inserted, be sure that it is long enough, and add extra pause commands (,) if necessary. 4. If the connection is established, but the time is not set correctly, verify that the lines printed on the screen show the correct date and time. If 1200-bits/s service is selected, the first number on each line is the Modified Julian Day (MJD) Number, which advances by 1 every day and is about 47000 in 1988. It is not used by the program. The next numbers are year, month, day, hour, minute and second in order, where the hour is in Universal Time (UTC), followed by the Daylight Savings flag, which is an integer from 0 to 99. The remainder of the line is not used by the program. If 300-bits/s service is selected, each line contains the time, the estimated line delay in milliseconds and the terminating character that is used for synchronization. As discussed above, the time is not set in this mode, so that only the presence of the terminating character is significant. If the lines are partially garbled then either the telephone line or the modem should be suspected. If the lines are totally garbled, it is likely that the modem cannot communicate at the selected speed or does not conform to the corresponding standard. It is also possible that there is a problem with the receive portion of the COM port, although this is less likely since the dialing commands use the same hardware. 5. If only the CMOS clock is not set correctly (using 1200 bits/s service), verify that it conforms to the IBM standard and that the configuration file is set correctly. 6. If you select output pulses on the line-printer port (LPT1), be sure that the line printer is not connected and that only pins 1 and 25 on the printer interface connector are connected to the external device that uses the pulses (the pulse appears on pin 1, and pin 25 is ground). If the line-printer is left connected and on-line, then each output pulse will send a random character to the printer. The printer will respond to these transmissions in unpredictable ways, and subsequent print operations may not work properly as a result. It may be necessary to re-boot the system in this case. Error Handling The program deals with only certain types of errors: Syntax errors in the configuration file are likely to be detected, although the program does not place any limits on the telephone number, and an error in specifying it is unlikely to be sensed until the modem responds erratically. Hardware problems or inconsistencies between the hardware and the configuration file will also be sensed since they will most likely result in no response from the modem or in a protocol error. The most likely source of error in a nominally healthy and properly configured system is a transmission error. We can distinguish several different types of problem depending on where the error occurs. 1. The line terminating character (* or #) is garbled or lost. The program will not detect the end of the line and will concatenate the line with the following one. If output pulses are enabled, no pulse will be sent. If the line in error is the line that is used either for setting the clock or checking it, then an error of 1 second will occur either in setting the clock or in comparing it. If this is not either of those lines then the program will simply continue with no error (the other lines are displayed but are not used in any other way). Since the length of the line is known, this error could be detected in principle, but the current version of the program does not do so. 2. Another character on the line is converted to the terminator (* or #). The program will detect a premature end-of-line and synchronization with the NBS will likely be affected. If output pulses are enabled, a pulse will be sent at the wrong time. The error introduced in setting the clock depends on which line this occurs in just as in 1 above. Note that this error is rather unlikely since there are 128 characters that an error might produce, but only 2 of them are legal terminators. This error could also be detected in principle by a line-length check as above, but the current version of the program does not do so. <*1> 3. A digit of the time is transformed into another character that is not a digit. This could be detected in principle by carefully checking each character on the line, but the current version of the program does not do so. If the line in error is used neither to set the time nor to check it, then the error will have no effect. The computer clock is not set until two consecutive lines whose times differ by exactly one second are received, so that two identical transmission errors must occur at the same place in two consecutive lines for the clocks to be set incorrectly. This is unlikely, but not impossible. If this is the line that is used to check the clock then the discrepancy between the local time and the NBS time is likely to be large, since the error is unlikely to be confined to the least significant digit of the seconds. If output pulses are enabled, this type of error has no effect on them since they are governed only by the receipt of the terminating character. <*1> 4. A digit of the time is transformed into another legal digit. This error cannot be detected by examining the line. The probability is rather small, however, since there are only 10 legal digits out of 128 possibilities. As with 3 above, if this is the line that is used to check the time, the discrepancy between the local time and the NBS time is likely to be large since the transmission error is unlikely to be confined to the least significant digit of the seconds. As in 3 above, there is no degradation of the output pulse timing. Errors 3 and 4 could also be dealt with by assuming some previous knowledge of the time or date and rejecting values that deviated from this assumed date and time by too great an amount. Illegal month and day combinations could also be detected in this way. <*1> The probability that these errors will result in setting the time incorrectly has been minimized by insisting that the times of two consecutive transmissions differ by exactly one second. A general version of such a scheme is quite complex since it must cope with all of the peculiarities of the calendar, and only a simplified version has been implemented. The seconds value from the first line of the pair is decoded and examined. If it is greater than 57, then the comparison is postponed, since the following second may be the first second of a new minute. (Second number 58 is the last second of the current minute if a negative leap-second is imminent, second number 59 is usually the last second of the current minute and second number 60 will be the last second if a positive leap-second is imminent.) If the current second is less than 57, the seconds digits are converted to blanks and the remainder of the date and time are stored in a buffer as received. When the next line is received, the seconds value is extracted and tested for equality with the previous value +1. If this comparison succeeds, the remaining digits of the date and time (with the seconds field converted to blanks in both cases) are compared character by character (all characters must be the same). If either comparison fails a transmission error is assumed, and the process is begun again with the next two lines since the program has no way of knowing which of the two lines is in error. This process continues until two consecutive lines are decoded and are found to be consecutive or until the NBS hardware hangs up the telephone. Name: MAKCFG Usage: MAKCFG This program constructs a file named NBSTIME.CFG based on the answers to a series of questions. The program may be run from any directory of any disk, but is most conveniently run from the same directory in which program NBSTIME is located. The number of each question refers to the line of the output file that is being assembled. Thus questions 1a, 1b, ... are used to assemble the various parameters for the first line. The contents of each line are described in the description for the NBSTIME program. All of the acceptable responses for each question are listed as part of question. Alphabetic answers may be given in upper or lower case. All answers must be terminated with a carriage return (or enter), and this fact is denoted by the symbol <return> in the description for each response. If you respond to any question with ? <return>, additional information will be printed out and the question will be repeated. If your response is not one of the expected responses, the message, "I don't understand ..." is printed and the question is repeated. Your response is not passed to the program until the <return> key is pressed, so that errors may be erased using the delete key as usual and the corrected response may then be entered. If the expected response is a single letter or digit, then all characters after the first one on the line are ignored (and an error will occur if the first character is not one of the expected responses even if a subsequent character is okay). Thus if when either y <return> or n <return> is expected, you enter either y <return> or yes, we have no bananas <return>, the two responses will be treated identically since only the first character is parsed and the remainder of the line is discarded. (Note that the "no" in the middle of the second response is ignored since only the first character is examined.) This program checks to see if a configuration file already exists in your directory. If it finds the file, it will print a message and give you the choice of renaming the old file, over-writing the old file or stopping to think about it. If you choose to rename the file, the existing file will be renamed CONFIG.OLD immediately, and a new file named NBSTIME.CFG will be created. The renaming process will fail if a file named CONFIG.OLD already existed in the current directory, and the program will give up if that happens. You must then erase one of the configuration files or copy them to another directory or sub-directory so that the program won't find them. If the renaming operation succeeds, a new file named NBSTIME.CFG is then created. If you choose to over-write the existing configuration file or if the configuration file did not previously exist, a new file named NBSTIME.CFG is created in the current directory (with zero length). <*1> The program then asks which version of the program you are planning to use. If you select the BIOS version of the program, then only COM1 or COM2 can be used for communication; COM3 and COM4 can also be used if you select the direct-access version, and question 2a, which requests this information is modified accordingly. If you select the direct access version and if your response to the port specification is 'h' then an additional question asking for the hardware address of the port is also asked. <*2> It is also possible to generate configuration files for the other versions of the program using program MAKCFG. A question at the start asks you which version of NBSTIME you are using. The differences among the various configuration files are discussed in Appendix A. The various configuration parameters are not written to the file until all of the questions have been answered, and an empty file named NBSTIME.CFG will be left in your directory if the program does not run to completion. This might happen, for example, if you responded to any question with a control-c (pressing control key and c key together), since such a response will cause the program to stop immediately. <*1> Program MAKCFG allows you to specify your time zone by its letter. To use this capability, you should respond with a * when you are asked for your time zone. The program will then ask you to specify your time zone by letter. You may respond in either upper or lower case. Your answer is converted to a numerical offset according to the following table and the numerical offset is then stored in the file. Note that you cannot enter these letters in the configuration file directly, since NBSTIME does not recognize them (except for Z). Response Difference (hours) Response Difference(hours) Local - Universal Local - Universal A +1 N -1 B +2 O -2 C +3 P -3 D +4 Q -4 E +5 R -5 F +6 S -6 G +7 T -7 H +8 U -8 I +9 V -9 K +10 W -10 L +11 X -11 M +12 Y -12 Z 0 Note that the letter J is not assigned and that the zone centered on the prime meridian is assigned the letter Z. The zone centered on the international date line has two assignments (M and Y), which will yield the same time on different days; most of the inhabited areas in that zone are on the Western side of the date line and will therefore use M. Notes about Revisions Paragraphs marked with a <*> have been revised since the original edition of the documentation as follows: Original release 26 February 1988 <*1> 15 July 1988 <*2> 30 September 1988 The modifications to the software are described below: Original release 26 February 1988 First Modification 31 May 1988 This modification corrected an error in the conversion to local time. The error occurred if daylight savings time was in effect, if the conversion to daylight savings time was specified in the configuration file and if the program was run between 12:00:00 midnight and 12:59:59 am local daylight savings time. The conversion to local daylight savings time should advance the date in this case, since the corresponding standard times would be 11:00:00 pm and 11:59:59 pm on the previous day, but the program did not do this. This error does not occur at other times during the day or if daylight savings time is not in effect or is not enabled in the configuration file NBSTIME.CFG. The transition days at the beginning and end of daylight savings time were also handled correctly. The problem results from the interaction between the conversion to local standard time and the additional conversion for daylight savings time on the transition days at the beginning and end of the daylight savings time period. Since the transition occurs at 02:00:00 am local time, the conversion for daylight savings time on a transition day must be delayed until after the local time and date have been computed. On any other day or after 11:00:00 pm on a transition day, however, the conversion to daylight savings time may advance the date, and must therefore be performed before the local date can be known. We have modified the software so that conversions on transition days and on other days are handled separately. Second modification 15 July 1988 The second modification provides for several enhancements: 1. Two versions of the program are now supported: NBSTIMEB and NBSTIMED. The _B version uses the BIOS for input/output and the _D version accesses the hardware ports directly. The two versions can be produced from the same source files by editing the file NBSTIME.H (see comments in that module) and then recompiling the affected routines. The table below shows all of the modules comprised in both versions of NBSTIME. Modules that are affected by a change in NBSTIME.H are indicated by (nbstime.h) on the same line. Comments in each module describe the dependence. In some cases (such as dial.c and hangup.c), the difference is primarily in the values for constants that set the time-out delays, since program NBSTIMED is considerably faster than NBSTIMEB. 2. The program does not set the time of the computer clock unless two consecutive lines have times that differ by exactly one second. This is intended to prevent the time from being set erroneously as a result of a transmission error. 3. The telephone line status report in module dial.c has been modified. The previous version assumed that a modem response to a dial command was the final status of the call, and that a response containing an 'R' was produced either by NO ANSWER or NO CARRIER and was therefore reported an incomplete call. Some modems were found to send an intermediate status of RINGING. This version of the program differentiates between R as the first letter of the word and ER at the end. In the first case, an intermediate response is assumed and the program waits for a second message. In the second case an incomplete call is assumed and the program exits. Third modification -- 30 September 1988 The third modification consisted of the following changes: 1. This modification adds code to estimate the rate offset of the computer clock with respect to NBS. This is done by subtracting the difference between the computer clock and the NBS with the corresponding values read from the last line of the archive file. The second differences are normalized by the time that has elapsed between the two estimates. The result is converted to seconds per day and is printed on the terminal following the time difference. If the machine has a both a RAM and a CMOS clocks, then the rates of both clocks will be estimated. 2. Additional code has been added to enable the program to run on different computers. The additional code is activated by editing file nbstime.h (see the comments in that file for more details). The capabilities of the different versions are described in Appendix A. The following table lists all of the modules, their functions and their last revision. File nbstime.h is included in all of the modules, and the parameters defined in it govern the compilation. Module Depends Last Function of Name on modified Module nbstime.h #3 Defines parameters that control compilation rdline.c (nbstime.h) #3 Main program wrtbuf.c (nbstime.h) #3 Write string of characters to port. rdbuf.c (nbstime.h) #3 Read string of characters from port. inilin.c (nbstime.h) #3 Determine hardware addresses and initialize. dial.c (nbstime.h) #3 Dial telephone number and report status. wait.c (nbstime.h) #3 Delay for 1 second. hangup.c (nbstime.h) #3 Hang-up telephone line and reset modem. parset.c (nbstime.h) #3 Parse received line and set clocks. cnvbcd.c (nbstime.h) #3 Convert binary to packed BCD. setcfg.c (nbstime.h) #3 Read configuration file and set parameters. sndptr.c (nbstime.h) #3 Send pulse to line printer port. diftim.c (nbstime.h) #3 Compute and display time difference. unpbcd.c (nbstime.h) #3 Convert packed BCD to binary. arcdif.c (nbstime.h) #3 Compute time difference and write to file. cmplst.c (nbstime.h) #3 Compare times of consecutive lines. getlst.c (nbstime.h) #3 Gets last line of archive file and parses it. makefile #3 input for make command on SUN system nbstime.prj #3 input for make command on IBM PC system Appendix A 1. The SUN version. This version of the software was developed on a SUN workstation, but should work with only minor modifications in other UNIX environments. Most UNIX environments keep time internally in units of seconds (and possibly fractions of a second) since 1 January 1970 Universal (Greenwich) Time. The conversion to local date and time is performed by the operating system as needed. The sun version of NBSTIME converts the time received from NBS to seconds since 1 January 1970 by subtracting 40587 (the MJD of 1 January 1970) from the received MJD, multiplying the difference by the number of seconds in a day (86400) and then adding the number of seconds equal to the received time. This result is used both for time comparisons and to set the computer clock, if necessary. In addition to the limitations discussed above (see the sections on Timing Accuracy and Error Handling), there are several other important considerations that are unique to this version. Although any user may compare the computer time with NBS, setting the time on the computer is a privileged operation that requires super-user status. The program will not complain about a request to set the time by a user who is not the super-user, but the operation will be rejected by the operating system. In addition, changing the clock in a multi-user, multi-processing environment may adversely affect the operation of user tasks scheduled via "cron" and background real-time processes ("daemons"). In extreme cases, the causality that is necessary for the proper operation of commands such as "make" might be violated. Finally, the program may not echo the on-time marker promptly if the system is heavily loaded or if the task is run through a window. The sun version of the software uses the same source code files as the IBM PC version. The header file nbstime.h must be edited to define the constant SUN and to remove the definition of the constants IBMPC and BIOS. This process is described in the comments in file nbstime.h. The SUN Configuration File The configuration file for the sun system differs somewhat from the version that is used by the IBMPC version. The SUN version may be produced with any text editor. Program MAKCFG may also be used. Line 1. This line is used to specify the telephone number. It is identical to the IBM PC version. See the discussion above for more details. Line 2. The first two characters specify the communication port. There are three different possibilities: a. <a><b> specifies port /dev/tty<a><b> b. <a> - specifies port /dev/tty<a> c. - specifes that the port will be defined on line 3. where <a> and <b> are two characters chosen from a - z or A - Z or 0 - 9. Note that case is significant: AB specifies /dev/ttyAB whereas b- specifies /dev/ttyb. Note that if the first character is -, the second character is not used and the characters specified below follow immediately starting in column 2. The next characters on the line are: E/e/B/b Echo/Blind dialing. See description for IBM PC H/h/L/l 1200/300 speed. See description for IBM PC S/s/D/d Set/Check clock. See description for IBM PC a/A/n/N Archive and rate See description for IBM PC These characters must appear in the order shown with no embedded spaces. All of these parameters have the same effect as in the IBMPC version. Note that it is not possible to send a pulse to the line-printer port in the sun version. Line 3. If the first character of line 2 was a -, then the path of the communications port is specified here as a string of characters. The string will be passed directly to the operating system and is not checked or parsed. Thus instead of specifying <a> - at the start of line 2, you could equally well put a - at the start of line 2 (followed by the other parameters as appropriate) and put /dev/ttya on line 3. If the port is fully specified on line 2 then this line is not needed.